package com.kktoolbox.entity;

import lombok.Data;
import lombok.NonNull;

/**
 * PDF搜索结果数据类
 * 
 * <p>该类用于封装搜索到的PDF文件的基本信息，
 * 作为搜索结果在应用程序各组件间传递数据。</p>
 * 
 * <p>主要包含的信息：</p>
 * <ul>
 *   <li>文件名：不包含路径的纯文件名</li>
 *   <li>文件路径：文件的完整绝对路径</li>
 *   <li>文件大小：以字节为单位的文件大小</li>
 * </ul>
 * 
 * <p>该类使用Lombok的@Data注解自动生成getter/setter/toString/equals/hashCode方法，
 * 减少样板代码并提高代码可维护性。</p>
 * 
 * <p>使用示例：</p>
 * <pre>{@code
 * PDFSearchResult result = new PDFSearchResult(
 *     "document.pdf", 
 *     "C:/Documents/document.pdf", 
 *     1024000L
 * );
 * logger.info("找到文件: {}", result.getFileName());
 * }</pre>
 * 
 * @author KK-Toolbox
 * @version 1.0.0
 * @since 2025-01-01
 */
@Data
public class DecumentSearchResult {
    
    /** 文件名（不包含路径） */
    @NonNull
    private String fileName;
    
    /** 文件的完整绝对路径 */
    @NonNull
    private String filePath;
    
    /** 文件大小，以字节为单位 */
    private long fileSize;
    
    /**
     * 构造函数 - 创建PDF搜索结果对象
     * 
     * <p>使用提供的文件信息创建一个新的搜索结果实例。
     * 所有参数都是必需的，不应为null。</p>
     * 
     * @param fileName 文件名，不应包含路径分隔符
     * @param filePath 文件的完整绝对路径
     * @param fileSize 文件大小，以字节为单位，应为非负数
     * 
     * @throws IllegalArgumentException 如果fileName或filePath为null或空字符串
     * @throws IllegalArgumentException 如果fileSize为负数
     */
    public DecumentSearchResult(@NonNull String fileName, @NonNull String filePath, long fileSize) {
        // 参数验证
        if (fileName.trim().isEmpty()) {
            throw new IllegalArgumentException("文件名不能为空");
        }
        if (filePath.trim().isEmpty()) {
            throw new IllegalArgumentException("文件路径不能为空");
        }
        if (fileSize < 0) {
            throw new IllegalArgumentException("文件大小不能为负数");
        }
        
        this.fileName = fileName.trim();
        this.filePath = filePath.trim();
        this.fileSize = fileSize;
    }
    
    /**
     * 获取格式化的文件大小字符串
     * 
     * <p>将字节大小转换为人类可读的格式，
     * 自动选择合适的单位（B、KB、MB、GB）。</p>
     * 
     * @return 格式化的文件大小字符串，例如"1.5 MB"
     */
    public String getFormattedFileSize() {
        if (fileSize < 1024) {
            return fileSize + " B";
        } else if (fileSize < 1024 * 1024) {
            return String.format("%.1f KB", fileSize / 1024.0);
        } else if (fileSize < 1024 * 1024 * 1024) {
            return String.format("%.1f MB", fileSize / (1024.0 * 1024.0));
        } else {
            return String.format("%.1f GB", fileSize / (1024.0 * 1024.0 * 1024.0));
        }
    }
}